XML reference

This section describes the six tags and their attributes in detail. It also contains the DTD (Document Type Definition) used to validate Resource XML and then describes each of the six tags, detailing the attributes supported by the tag.

The following DTD can be used to validate the resource XML:

<!ELEMENT resource (location)+>
<!ATTLIST resource
	visible (no|yes) "no"
>
<!ELEMENT location (if|value|text|title)*>
<!ELEMENT if (if|value|text|title)*>
<!ATTLIST if
	column CDATA #REQUIRED
	filled (no|yes) #IMPLIED
	rows CDATA "1"
	value CDATA #IMPLIED
>
<!ELEMENT value EMPTY>
<!ATTLIST value
	column CDATA #REQUIRED
	format (none|url) "none"
	rows CDATA "1"
	separator CDATA " "
>
<!ELEMENT text (#PCDATA)>
<!ELEMENT title (if|value|text)>

The <resource> tag is the outermost tag of a Resource definition. It is used to enclose the definition. A <resource> tag must contain one or more <location> tags.

Attributes 

     visible="no|yes"

The visible attribute determines what should occur if a Resource does not produce a document path: normally the Resource title will not be shown under the Resources sub menu. If the visible attribute is set to yes, the title is shown even when there is no document path produced, but it is disabled (greyed out). The default case is visible="no".

The <location> tag is used to define a single instance of a document path. A Resource can contain one or more <location> tags. When determining the document path for a given Resource, each <location> section is evaluated one after another, starting from the top, until a non-empty document path is generated. Thus the Boolean relationship between each <location> section is OR. A <location> element can contain a combination of <if>, <value> and <text> tags.

Attributes 

     None

The <text> tag is used to output text to build a document path. The text element outputs the characters found between the opening and closing tags. The text is not interpreted in any way (in essence it is treated as CDATA). A text element cannot contain any other tags.

Attributes 

     None

The <value> tag retrieves the data from the specified column and outputs it as part of the document path. The most common use of the value element is to include data as search terms in a query based URL. A value element cannot contain any other tags.

Attributes 

     column="colname"

The column attribute names the data column from which the data is to be extracted. The name is the column name as used by the EMu client (see Field Help for details about locating the column name). Support is provided for atomic, table and nested table columns. For tables and nested tables the rows attribute determines what data is retrieved. In order to provide efficient data access, a cache of column values is maintained. The column attribute is mandatory.

     rows="rows"

When the nominated column is a table or nested table, the rows attribute determines which values are used. The value can be one of three formats. The first format is just a row number. Row numbers are one based (the first row is number one). Thus a tag of:

     <value column="NamRoles_tab" rows="1"/>

means that the returned value will be the first row in the NamRoles_tab table.

The second format is a range of rows, e.g. rows="1-5", indicating that the first five rows are to be retrieved from the NamRoles_tab table. If there are less than five rows, all available rows are returned.

Finally the keyword all may be used to indicate that all rows in a table or nested tab should be retrieved (i.e. rows="all").

Note that nested tables are flattened before rows are extracted. This allows the rows to be treated as a single table of values. The default value for rows is "1".

     separator="string"

When more than one value is extracted from a table, the separator attribute is used to indicate how the rows in the table should be joined. The string sequence is placed between each row in the table. For example, the tag:

     <value column=NamRoles_tab rows="all" separator="+"/>

will get all values in the NamRoles_tab field and join them together with a "+" character between each value (the "+" character is used to encode a space in a URL). The default value for separator is " " (a space).

     format="none|url"

Once the value is retrieved, the format attribute is used to determine how the data should be encoded. A value of none results in the data being output without any encoding taking place. In order to transmit data correctly via a URL, a format of url should be used. For more information on URL encoding see http://www.rfc-editor.org/rfc/rfc1738.txt. The default value is none.

The <if> tag is used to test values. It is the only conditional tag provided for Resource generation. The tag allows you to check whether a column contains a value or not, or whether a certain value appears in a column. If the tag evaluates to true, all inner tags (that is all tags down to the closing </if> tag) are evaluated, otherwise they are ignored. An <if> tag will generally contain text, values and other if elements.

Attributes 

     column="colname"

The column attribute names the data column whose data is to be tested. The name is the column name as used by the EMu client. Support is provided for atomic, table and nested table columns. For tables and nested tables the rows attribute determines what data is retrieved. The column attribute is mandatory.

     rows="rows"

When the selected column is a table or nested table, the rows attribute determines which values are used. The value can be one of three formats. The first format is a single row number. Row numbers are one based (the first row is number one).

The second format is a range of rows, e.g. rows="1-5", indicating that the first five rows are to be retrieved from the NamRoles_tab table. If there are less than five rows, all available rows are returned.

Finally the keyword all may be used to indicate that all rows in a table or nested tab should be retrieved (i.e. rows="all").

Note that nested tables are flattened before the rows are extracted. This allows the rows to be treated as a single table of values. The default value for rows is "1".

     filled="no|yes"

The filled attribute is used to test whether a column contains a value. If the column is a table or nested table, filled checks whether the table contains any value. A value of yes indicates that the column must contain a value for the condition to be true; a value of no specifies that the column should not contain a value to evaluate to true.

     value="string"

The value attribute allows you to test for the existence of a value in the data. If the supplied string appears as one of the values in the column, the tag evaluates to true, otherwise false. Comparison of the string against the data is case insensitive.

The <title> tag is used to replace the sub menu caption displayed under Tools>Resources. The caption is exchanged with any output generated by <text> and <value> tags appearing between the start and end <title> tags. <if> tags can be used to control conditionally what text is generated. If the menu caption is altered by this tag, the position of the menu entry is not changed. Thus, you can use the Registry entry title to define the menu order (via the alphabetic sort) and then alter the caption shown using this tag.

Attributes 

     None